ContextualMenu Class

Used to display and control contextual menus.

Events

Action

Properties

Methods

More information available in parent classes: Control:Object

Because this is a Control, see the Control class for other properties and events that are common to all Control objects.

Notes

The ConstructContextualMenu events of the Window and RectControl class are the recommended places to create contextual menus. It takes as a parameter a MenuItem that serves the role as the 'menubar' for a contextual menu. Any menu items that you add to this menu bar are displayed when you return True from this event.

The ConstructContextualMenu event will fire when the time is right to display the contextual menu. This is not restricted to mouse-related events and, for mouse events, it can vary by platform. On Macintosh, it is displayed on a MouseDown event; for Windows and Linux, it is displayed on MouseUp. Also, the user may have pressed the contextual menu key on a Windows keyboard or pressed Shift+F10 instead of clicking the mouse. The ConstructContextualMenu event simplifies all this for you by just firing whenever the user has requested the contextual menu in the window or the control.

If you build your contextual menu in the ConstructContextualMenu and have no Menu Handlers for the items, you handle the selected menu item with the ContextualMenuAction event. It is passed the selected MenuItem from the contextual menu and you can inspect its Text or Tag property to determine which item was selected.

All of this eliminates the need for the ContextualMenu control and the IsContextualClick function.

See the RectControl entry for an example of these two event handlers.

Using the ContextualMenu Control

Contextual menus are created in the same way PopupMenu controls are. However, they are no longer needed if you use the ConstructContextulMenu and ContextualMenuAction event handlers.

If you have a static set of items for a contextual menu, you can build the menu in the ContextualMenu's Open event handler. If the items in the menu change, you may want to build the contextual menu on the fly--after testing IsContextualClick--in a MouseDown event handler. To display the contextual menu, call its Open method.

You display a contextual menu by calling the Popup method of the MenuItem class. This method displays the MenuItem as a contextual menu. When the user chooses a menu item, it will first try to fire the MenuItem's Action event handler. If that returns False or is not implemented, then it will try its menu handlers. If those return False or are not implemented, it will return the MenuItem that was selected. If any of these handlers returned True (indicating that the action was handled), then the Popup method returns Nil.

If these methods fail to handle the menu selection, the ContextualMenuAction event is fired. It gives you a chance to handle the menu selection by inspecting the Text and/or Tag properties of the selected menu item.

There are two choices for implementing contextual menus when you have more than one control in a window that requires a contextual menu. The simplest method is to add one ContextualMenu control for each control that requires a contextual menu. The second method would require you to add a property of type Control or RectControl to the window and store a reference to the object that requires the display of a contextual menu. Then a single ContextualMenu control can be used to display and control the contextual menus because it can use the property you have added to determine which object the user is clicking. This second method is a bit more complex but will be more efficient when you have several controls in a window that all require the same contextual menu.

Example

The following code in a ContextualMenu's Open event handler populates the control:

Dim s as String
Dim i,last as Integer
s="Undo,-,Cut,Copy,Paste" //dash adds a separator below Undo
last= CountFields(s,",")
For i=1 to last
Me.addRow NthField(s,",",i)
Next

The following code in a control's MouseDown event handler displays the contextual menu when the user right+clicks in the control (or Control-clicks on Macintosh):

If IsContextualClick then
ContextualMenu1.open
Return True
End if

When the user chooses a menu item, the ContextualMenu's Action event handler runs. The selected menu item is passed to the event handler, so you know which item the user has chosen.